.TH SHUTTLE "1" "2011-01-13" "LinuxCNC Documentation" "HAL User's Manual"
.de TQ
.br
.ns
.TP \\$1
..
.SH NAME
shuttle \- control HAL pins with the ShuttleXpress or ShuttlePRO device made by Contour Design
.SH SYNOPSIS
\fIloadusr\fR \fBshuttle\fR \fI[DEVICE ...]\fR
.SH DESCRIPTION
shuttle is a non-realtime HAL component that interfaces Contour
Design's ShuttleXpress and ShuttlePRO devices with LinuxCNC's HAL.

.PP
If the driver is started without command-line arguments, it will probe all
/dev/hidraw* device files for Shuttle devices, and use all devices found.
If it is started with command-line arguments, it will only probe the
devices specified.

.PP
The ShuttleXpress has five momentary buttons, a 10 counts/revolution
jog wheel with detents, and a 15-position spring-loaded outer wheel that
returns to center when released.

.PP
The ShuttlePRO has 13 momentary buttons, a 10 counts/revolution
jog wheel with detents, and a 15-position spring-loaded outer wheel that
returns to center when released.

.SH UDEV
The shuttle driver needs read permission to the Shuttle devices'
/dev/hidraw* device files.  This can be accomplished by adding a file
\fB/etc/udev/rules.d/99-shuttle.rules\fR, with the following contents:

SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0b33", ATTRS{idProduct}=="0020", MODE="0444"

SUBSYSTEM=="hidraw", ATTRS{idVendor}=="05f3", ATTRS{idProduct}=="0240", MODE="0444"

The LinuxCNC Debian package installs an appropriate udev file
automatically, but if you are building LinuxCNC from source and are not
using the Debian packaging, you'll need to install this file by hand.

.SH A warning about the Jog Wheel
The Shuttle devices have an internal 8-bit counter for the current
jog-wheel position.  The shuttle driver can not know this value
until the Shuttle device sends its first event.  When the first
event comes into the driver, the driver uses the device's reported
jog-wheel position to initialize counts to 0.

This means that if the first event is generated by a jog-wheel move,
that first move will be lost.

Any user interaction with the Shuttle device will generate an event,
informing the driver of the jog-wheel position.  So if you (for example)
push one of the buttons at startup, the jog-wheel will work fine and
notice the first click.

.SH Pins

All HAL pin names are prefixed with the type of device followed by
the index of the device (the order in which the driver found them),
for example "shuttlexpress.0" or "shuttlepro.2".

.TP
(bit out) \fI(prefix).button-(number)\fR
.TP
(bit out) \fI(prefix).button-(number)-not\fR

    The momentary buttons.  "(number)" identifies which button corresponds
    to the HAL pin.  The "button-(number)" pins are True when the button
    is pushed, the "button-(number)-not" pins are True when the button
    is not pushed.

.TP
(s32 out) \fI(prefix).counts\fR

    Accumulated counts from the jog wheel (the inner wheel).

.TP
(s32 out) \fI(prefix).spring-wheel-s32\fR

    The current deflection of the spring-wheel (the outer wheel).
    It's 0 at rest, and ranges from -7 at the counter-clockwise
    extreme to +7 at the clockwise extreme.

.TP
(float out) \fI(prefix).spring-wheel-f\fR

    The current deflection of the spring-wheel (the outer wheel).
    It's 0.0 at rest, -1.0 at the counter-clockwise extreme, and +1.0 at
    the clockwise extreme.  (The Shuttle devices report the spring-wheel
    position as an integer from -7 to +7, so this pin reports only 15
    discrete values in its range.)

